主题
视频处理模块总览 - Overview
本分类做什么
对 视频文件 与 摄像头 进行 打开、查询属性、按帧/时间读取、跳转、导出帧、简单编辑（剪切/转码/缩放） 及 场景/运动/亮度 等分析。读出的帧多为 OLAImage 或文件，可再交给 图像处理、图像识别。
一、打开与关闭：文件 vs 摄像头
| 接口 | 差异 |
|---|---|
| OpenVideo | 打开 视频文件（路径）。 |
| OpenCamera | 打开 摄像头（设备索引，默认规格）。 |
| OpenCameraByName | 按 设备名称 打开，多摄像头时比纯索引更稳。 |
| OpenCameraEx | 按索引或友好名打开，并在首帧前协商宽高 / 帧率 / FOURCC。 |
| EnumCameras | 不占用设备，枚举本机摄像头及驱动报告的像素规格。 |
| SetCameraFormat | 修改已打开摄像头句柄的像素大小和帧率。 |
| GetBindCameraInfo | 读取 display="camera" 绑定后的实际像素大小与协商结果。 |
| CloseVideo | 释放句柄与解码资源。 |
| IsVideoOpened | 查询是否已成功打开。 |
选型：磁盘上的 mp4/avi 等 → OpenVideo；只要默认画面 → OpenCamera / OpenCameraByName；要指定分辨率 → 先 EnumCameras，再 OpenCameraEx。
把摄像头当作截图源（Capture / FindPic）时，用 BindWindowEx 的 display="camera"，设备与分辨率走 SetConfig 的 Camera*。这条路径与上面的视频句柄相互独立。
读像素大小：
| 时机 | 接口 |
|---|---|
| 绑定 / 打开前 | EnumCameras 的 formats[].width / height |
| OpenCamera / OpenCameraEx 之后 | GetVideoWidth / GetVideoHeight；GetVideoInfo 的 actual |
display="camera" 绑定之后 | GetClientSize（hwnd 可传 0）；GetBindCameraInfo 的 actual.width / actual.height |
二、属性查询：宽高、时长、帧率
| 接口 | 内容 |
|---|---|
GetVideoInfo | 综合信息（以详情页字段为准）。 |
GetVideoWidth、GetVideoHeight | 像素尺寸。摄像头句柄返回协商后的实际宽高。 |
GetVideoFPS | 帧率。 |
GetVideoTotalFrames、GetVideoDuration | 总帧数、时长。 |
差异：部分格式 可变帧率 或 元数据缺失 时，返回值可能与实际逐帧遍历略有出入，以详情页说明为准。
三、读帧与跳转
| 接口 | 差异 |
|---|---|
ReadNextFrame | 顺序 下一帧，适合顺序扫描。 |
ReadFrameAtIndex、ReadFrameAtTime | 随机访问：按 帧号 或 时间戳。 |
ReadCurrentFrame | 当前位置一帧（配合 Seek 后使用）。 |
SeekToFrame、SeekToTime、SeekToBeginning、SeekToEnd | 定位；部分容器 关键帧对齐，非逐帧精确见详情页。 |
GetCurrentFrameIndex、GetCurrentTimestamp | 查询当前读指针位置。 |
选型：顺序抽帧 → ReadNextFrame；要做 剪辑点检测 → SeekToTime + 读帧对比。
四、批量导出与缩略图
| 接口 | 差异 |
|---|---|
ExtractFramesToFiles、ExtractFramesByInterval | 批量落盘，按列表或 时间间隔。 |
ExtractKeyFrames | 关键帧 提取，体积小于逐帧。 |
SaveCurrentFrame、SaveFrameAtIndex | 单帧保存。 |
ExtractSingleFrame、ExtractThumbnail、GetVideoInfoFromPath | 免完全打开 的快速信息/首帧（以详情页能力为准）。 |
五、编辑与合成
| 接口 | 说明 |
|---|---|
ConvertVideo、ResizeVideo、TrimVideo | 转码、分辨率、剪切时间片段。 |
CreateVideoFromImages | 由 图片序列 生成视频。 |
六、分析类（非解码即结束）
| 接口 | 用途 |
|---|---|
CalculateFrameSimilarity | 两帧相似度。 |
DetectSceneChanges | 场景切换点。 |
DetectMotion | 运动区域/强度（见详情页）。 |
CalculateAverageBrightness | 平均亮度。 |
IsValidVideoFile | 文件是否可读。 |
与 图像识别 区别：本分类偏 视频时间轴；Match*/Find* 偏 单帧内找模板。
七、快速选型
| 需求 | 建议 |
|---|---|
| 抽第 N 秒一帧做 OCR | SeekToTime + ReadCurrentFrame + 文字识别 |
| 监控摄像头是否断流 | IsVideoOpened + 定时 ReadNextFrame 失败重试 |
| 指定分辨率打开摄像头 | EnumCameras + OpenCameraEx |
| 摄像头当截图源找图 | SetConfig 的 Camera* + BindWindowEx(display="camera") + Capture / FindPic |
| 只要封面图 | ExtractThumbnail 或 ReadFrameAtIndex(0) |